<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
            "http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>



<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<META name="GENERATOR" content="hevea 1.08">
<LINK rel="stylesheet" type="text/css" href="embroot.css">
<TITLE>
To get started
</TITLE>
</HEAD>
<BODY >
<A HREF="embroot003.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="embroot005.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
<HR>

<H2 CLASS="section"><A NAME="htoc3">2.1</A>&nbsp;&nbsp;To get started</H2><UL>
<LI><A HREF="embroot004.html#toc1">Directories</A>
<LI><A HREF="embroot004.html#toc2">Definitions</A>
<LI><A HREF="embroot004.html#toc3">Compiling, linking and running on Unix/Linux</A>
<LI><A HREF="embroot004.html#toc4">Compiling, linking and running on Windows</A>
</UL>


This section is about the prerequisites for working with
ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> in your development environment. The directory structure,
the libraries and the include files are described.<BR>
<BR>
<A NAME="toc1"></A>
<H3 CLASS="subsection"><A NAME="htoc4">2.1.1</A>&nbsp;&nbsp;Directories</H3>
<A NAME="@default1"></A>
The libraries and include files needed to use ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> as an
embedded component are available under the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>
<A NAME="@default2"></A>
directory which was set-up during installation. If you have access
to a stand-alone ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> it can be found using the following query
at the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> prompt:
<PRE CLASS="verbatim">
    [eclipse 1]: get_flag(installation_directory,Dir).

    Dir = "/usr/local/eclipse"
    yes.
    [eclipse 2]
</PRE>
We will assume from here that ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> was installed in "/usr/local/eclipse".<BR>
<BR>
You would find the include files in "/usr/local/eclipse/include/$ARCH"
and the the libraries in "/usr/local/eclipse/lib/$ARCH" where
"$ARCH" is a string naming the architecture of your machine.
<A NAME="@default3"></A>
<A NAME="@default4"></A>
This can be found using the following ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> query:
<PRE CLASS="verbatim">
    [eclipse 2]: get_flag(hostarch,Arch).

    Arch = "sun4"
    yes.
    [eclipse 3]:
</PRE>
You will need to inform your C or C++ compiler and linker about these
directories so that these tools can include and link the appropriate files.
A make file "Makefile.external" can be found together with the libraries.
<A NAME="@default5"></A>
The definitions in that makefile may have to be updated according to
your operating system environment.<BR>
<BR>
A set of example C and C++ programs can be found in
"/usr/local/eclipse/doc/examples".<BR>
<BR>
When delivering an application you will have to include with it the
contents of the directory 
"/usr/local/eclipse/lib" without which ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>
cannot work. Normally this would be copied into the directory structure
of the delivered application. The interface can set different values
for this directory, enabling different applications to have different
sets of libraries.<BR>
<BR>
<A NAME="toc2"></A>
<H3 CLASS="subsection"><A NAME="htoc5">2.1.2</A>&nbsp;&nbsp;Definitions</H3>
To include the definitions needed for calling the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> library
in a C program use:
<A NAME="@default6"></A>
<PRE CLASS="verbatim">
    #include &lt;eclipse.h&gt;
</PRE>
For C++ a more convenient calling convention can be used based on
some classes wrapped around these C definitions. To include these use:
<PRE CLASS="verbatim">
    #include &lt;eclipseclass.h&gt;
</PRE>
<A NAME="toc3"></A>
<H3 CLASS="subsection"><A NAME="htoc6">2.1.3</A>&nbsp;&nbsp;Compiling, linking and running on Unix/Linux</H3>
Assuming that the environment variable ECLIPSEDIR is set to the
ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> installation directory and the environment variable ARCH is set to
the architecture/operating system name,
an application can be built as follows:
<PRE CLASS="verbatim">
gcc -I$ECLIPSEDIR/include/$ARCH eg_c_basic.c -L$ECLIPSEDIR/lib/$ARCH -leclipse
</PRE>This will link your application with the shared library <CODE>libeclipse.so</CODE>.<BR>
<BR>
At runtime, your application must be able to locate <CODE>libeclipse.so</CODE>.
This can be achieved by adding <I>ECLIPSEDIR</I>/<I>lib</I>/ARCH to your
<CODE>LD_LIBRARY_PATH</CODE> environment variable.<BR>
<BR>
The embedded ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> finds its own support files (e.g. ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> libraries)
through the <CODE>ECLIPSEDIR</CODE> environment variable.
This must be set to the location where ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> is installed,
e.g. <CODE>/usr/local/eclipse</CODE>.
Alternatively, the application can invoke <CODE>ec_set_option</CODE> to specify
the <CODE>ECLIPSEDIR</CODE> location before initialising the embedded ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>
with <CODE>ec_init</CODE>.<BR>
<BR>
<A NAME="toc4"></A>
<H3 CLASS="subsection"><A NAME="htoc7">2.1.4</A>&nbsp;&nbsp;Compiling, linking and running on Windows</H3>
If you use GCC, you can link either directly against <CODE>eclipse.dll</CODE>
or against <CODE>eclipse.dll.a</CODE>.
The required command line is similar to the Unix case.<BR>
<BR>
If you use a Microsoft compiler, make sure you have the following
additional settings in your C/C++ compiler/development system:
<UL CLASS="itemize"><LI CLASS="li-itemize">
In the <B>C/C++ Preprocessor</B> settings,
specify the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> include directory as an additional
include directory, e.g. <CODE>C:\Program Files\ECLiPSe 5.10\include\i386_nt</CODE>.
<LI CLASS="li-itemize">In the <B>Link</B> settings,
specify <CODE>eclipse.lib</CODE> as an additional object/library
module, and the location of this library, e.g.
<CODE>C:\Program Files\ECLiPSe 5.10\lib\i386_nt</CODE> as an additional library path.
</UL>
<A NAME="@default7"></A>
Moreover, you need to create an <CODE>eclipse.lib</CODE> for the compiler to
link against. This file can be created from <CODE>eclipse.def</CODE> and
<CODE>eclipse.dll</CODE> (which are part of the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> distribution),
using the <CODE>lib.exe</CODE> or <CODE>link.exe</CODE> tool (which comes with the
C/C++ development system).
<PRE CLASS="verbatim">
    cd C:\Program Files\ECLiPSe 5.10\lib\i386_nt
    lib.exe /def:eclipse.def
</PRE>Warnings about import directives can be ignored.
If you do not have <CODE>lib.exe</CODE>, try instead
<PRE CLASS="verbatim">
    link.exe /lib /def:eclipse.def
</PRE>
At runtime, your application must be able to locate <CODE>eclipse.dll</CODE>,
<A NAME="@default8"></A>
i.e. you should either
<UL CLASS="itemize"><LI CLASS="li-itemize">
copy <CODE>eclipse.dll</CODE> into the folder where your application is located, or
<LI CLASS="li-itemize">copy <CODE>eclipse.dll</CODE> into one of Windows' standard library folders, or
<LI CLASS="li-itemize">add the path to the folder where <CODE>eclipse.dll</CODE> can be found
	to your PATH environment variable.
</UL>
The <CODE>eclipse.dll</CODE> finds its own support files (e.g. ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> libraries)
through the <CODE>ECLIPSEDIR</CODE> registry entry under the registry key
<CODE>HKEY_LOCAL_MACHINE\SOFTWARE\IC-Parc\ECLiPSe\X.Y</CODE> (X.Y is the version
number).
This must be set to the location where ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> is installed,
e.g. <CODE>C:/Eclipse</CODE>.
Alternatively, the application can invoke <CODE>ec_set_option</CODE> to specify
the <CODE>ECLIPSEDIR</CODE> location before initialising the embedded ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>
with <CODE>ec_init</CODE>.<BR>
<BR>
<HR>
<A HREF="embroot003.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="embroot005.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
</BODY>
</HTML>
